这段代码是libHaru库的一部分，它提供了创建和设置PDF文档中页码标签（Page Label）的功能。页码标签是用于标识文档中页面编号的系统，它允许用户自定义页码的格式和起始页码。

以下是代码中定义的关键函数及其功能概述：

1. **HPDF_PageLabel_New**：这个函数用于创建一个新的页码标签对象。它接受以下参数：
   - `pdf`：指向HPDF_Doc对象的指针，表示PDF文档。
   - `style`：一个HPDF_PageNumStyle枚举值，表示页码的样式。支持的样式包括十进制数字、大写罗马数字、小写罗马数字、大写字母和和小写字母。
   - `first_page`：整数值，表示页码编号的起始页码。
   - `prefix`：一个字符串，表示页码前的前缀。

2. 函数的工作流程如下：
   - 使用`HPDF_Dict_New`创建一个新的字典对象。
   - 根据提供的`style`参数，使用`HPDF_Dict_AddName`向字典中添加页码样式。
   - 如果提供了非空的`prefix`字符串，使用`HPDF_Dict_Add`向字典中添加前缀。
   - 如果`first_page`不为0，使用`HPDF_Dict_AddNumber`向字典中添加起始页码。
   - 如果在创建页码标签对象的过程中遇到任何错误，函数会释放已分配的资源并返回NULL。
   - 如果一切顺利，函数返回新创建的页码标签对象。

代码中的`HPDF_PTRACE`用于调试跟踪，帮助开发者了解函数的执行流程。`Fail`标签用于在发生错误时跳转到函数的清理和退出部分。

总的来说，`HPDF_PageLabel_New`函数为libHaru用户提供了一种灵活的方式来定义PDF文档的页码标签，允许他们根据需要定制页码的显示方式。/*
 * << Haru Free PDF Library >> -- hpdf_page_label.c
 *
 * URL: http://libharu.org
 *
 * Copyright (c) 1999-2006 Takeshi Kanno <takeshi_kanno@est.hi-ho.ne.jp>
 * Copyright (c) 2007-2009 Antony Dovgal <tony@daylessday.org>
 *
 * Permission to use, copy, modify, distribute and sell this software
 * and its documentation for any purpose is hereby granted without fee,
 * provided that the above copyright notice appear in all copies and
 * that both that copyright notice and this permission notice appear
 * in supporting documentation.
 * It is provided "as is" without express or implied warranty.
 *
 */

#include "hpdf_conf.h"
#include "hpdf_utils.h"
#include "hpdf_page_label.h"

HPDF_Dict
HPDF_PageLabel_New  (HPDF_Doc             pdf,
                     HPDF_PageNumStyle    style,
                     HPDF_INT             first_page,
                     const char     *prefix)
{
    HPDF_Dict obj = HPDF_Dict_New (pdf->mmgr);

    HPDF_PTRACE ((" HPDF_PageLabel_New\n"));

    if (!obj)
        return NULL;

    switch (style) {
        case HPDF_PAGE_NUM_STYLE_DECIMAL:
            if (HPDF_Dict_AddName (obj, "S", "D") != HPDF_OK)
                goto Fail;
            break;
        case HPDF_PAGE_NUM_STYLE_UPPER_ROMAN:
            if (HPDF_Dict_AddName (obj, "S", "R") != HPDF_OK)
                goto Fail;
            break;
        case HPDF_PAGE_NUM_STYLE_LOWER_ROMAN:
            if (HPDF_Dict_AddName (obj, "S", "r") != HPDF_OK)
                goto Fail;
            break;
        case HPDF_PAGE_NUM_STYLE_UPPER_LETTERS:
            if (HPDF_Dict_AddName (obj, "S", "A") != HPDF_OK)
                goto Fail;
            break;
        case HPDF_PAGE_NUM_STYLE_LOWER_LETTERS:
            if (HPDF_Dict_AddName (obj, "S", "a") != HPDF_OK)
                goto Fail;
            break;
        default:
            HPDF_SetError (&pdf->error, HPDF_PAGE_NUM_STYLE_OUT_OF_RANGE,
                    (HPDF_STATUS)style);
            goto Fail;
    }

    if (prefix && prefix[0] != 0)
        if (HPDF_Dict_Add (obj, "P", HPDF_String_New (pdf->mmgr, prefix,
                    pdf->def_encoder)) != HPDF_OK)
            goto Fail;

    if (first_page != 0)
        if (HPDF_Dict_AddNumber (obj, "St", first_page) != HPDF_OK)
            goto Fail;

    return obj;

Fail:
    HPDF_Dict_Free (obj);
    return NULL;
}

